home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / share / doc / python-debian / README.deb822 < prev    next >
Text File  |  2009-07-18  |  3KB  |  99 lines
  1. deb822.py README
  2. ================
  3.  
  4. The Python deb822 aims to provide a dict-like interface to various rfc822-like
  5. Debian data formats, like Packages/Sources, .changes/.dsc, pdiff Index files,
  6. etc. The benefit is that deb822 knows about special fields that contain
  7. whitespace separated sub-fields, and provides named access to them. For
  8. example, the "Files" field in Source packages, which has three subfields, or
  9. "Files" in .changes files, which has five. These are known as "multifields".
  10.  
  11. deb822 has no external dependencies, but can use python-apt if available to
  12. parse the data, which gives a very significant performance boost when iterating
  13. over big Packages files.
  14.  
  15. Key lookup in Deb822 objects and their multifields is case-insensitive, but the
  16. original case is always preserved, e.g. when printing the object.
  17.  
  18.  
  19. Classes
  20. =======
  21.  
  22. Here is a list of the types deb822 knows about:
  23.  
  24.   * Deb822 (aliases: Packages) - base class with no multifields.
  25.  
  26.   * Dsc (aliases: Sources) - class to represent .dsc files / Sources paragraphs.
  27.  
  28.     - Multivalued fields:
  29.  
  30.       ┬╖ Files: md5sum, size, name
  31.  
  32.   * Changes - class to represent a .changes file
  33.  
  34.     - Multivalued fields:
  35.  
  36.       ┬╖ Files: md5sum, size, section, priority, name
  37.  
  38.   * PdiffIndex - class to represent a pdiff Index file
  39.  
  40.     - Multivalued fields:
  41.  
  42.       ┬╖ SHA1-Current: SHA1, size
  43.       ┬╖ SHA1-History: SHA1, size, date
  44.       ┬╖ SHA1-Patches: SHA1, size, date
  45.  
  46.  
  47. Input
  48. =====
  49.  
  50. Deb822 objects are normally initialized from a file() object, from which
  51. at most one paragraph is read, or a string.
  52.  
  53. Alternatively, any sequence that returns one line of input at a time may
  54. be used, e.g. an array of strings.
  55.  
  56. PGP signatures, if present, will be stripped.
  57.  
  58.  
  59. Iteration
  60. =========
  61.  
  62. All classes provide an "iter_paragraphs" class method to easily go over
  63. each stanza in a file with multiple entries, like a Packages.gz file.
  64. For example:
  65.  
  66.     f = file('/mirror/debian/dists/sid/main/binary-i386/Sources') 
  67.  
  68.     for src in Sources.iter_paragraphs(f):
  69.     print src['Package'], src['Version']
  70.  
  71. This method uses python-apt if available to parse the file, since it
  72. significantly boosts performance. The downside, though, is that yielded
  73. objects share storage, so they should never be kept accross iterations.
  74. To prevent this behavior, pass a "shared_storage=False" keyword-argument
  75. to the iter_paragraphs() function.
  76.  
  77.  
  78. Sample usage (TODO: Improve)
  79. ============
  80.  
  81.    import deb822 
  82.  
  83.    d = deb822.dsc(file('foo_1.1.dsc'))
  84.    source = d['Source']
  85.    version = d['Version']
  86.  
  87.    for f in d['Files']:
  88.        print 'Name:', f['name']
  89.        print 'Size:', f['size']
  90.        print 'MD5sum:', f['md5sum']
  91.  
  92.     # If we like, we can change fields
  93.     d['Standards-Version'] = '3.7.2'
  94.  
  95.     # And then dump the new contents
  96.     new_dsc = open('foo_1.1.dsc2', 'w')
  97.     d.dump(new_dsc)
  98.     new_dsc.close()
  99.